# corexy运动系统,由toolhead模块加载时被加载
# 该运动系统负责三个轴的运动
#
# Copyright (C) 2017-2021  Kevin O'Connor <kevin@koconnor.net>
#
# This file may be distributed under the terms of the GNU GPLv3 license.
import logging, math
import stepper

class CoreXYKinematics:
    def __init__(self, toolhead, config):
        # 初始化xyz轴对应的PrinterRail轨道信息，轨道中保存stepper和限位器信息
        self.rails = [stepper.LookupMultiRail(config.getsection('stepper_' + n))
                      for n in 'xyz']
        # X轴的限位器关联Y轴电机
        for s in self.rails[1].get_steppers():
            self.rails[0].get_endstops()[0][0].add_stepper(s)
        # Y轴的限位器关联X轴电机
        for s in self.rails[0].get_steppers():
            self.rails[1].get_endstops()[0][0].add_stepper(s)
        # 设置不同轨道上的迭代求解器，设置步进器上的运动系统
        self.rails[0].setup_itersolve('corexy_stepper_alloc', b'+')
        self.rails[1].setup_itersolve('corexy_stepper_alloc', b'-')
        self.rails[2].setup_itersolve('cartesian_stepper_alloc', b'z')
        # 为所有步进器设置梯形速度队列
        for s in self.get_steppers():
            s.set_trapq(toolhead.get_trapq())
            # 注册步数生成器
            toolhead.register_step_generator(s.generate_steps)
        config.get_printer().register_event_handler("stepper_enable:motor_off",
                                                    self._motor_off)
        # 设置边界检查
        max_velocity, max_accel = toolhead.get_max_velocity()
        self.max_z_velocity = config.getfloat(
            'max_z_velocity', max_velocity, above=0., maxval=max_velocity)
        self.max_z_accel = config.getfloat(
            'max_z_accel', max_accel, above=0., maxval=max_accel)
        # xyz轴的边界,边界是（1，-1）表示没归位
        self.limits = [(1.0, -1.0)] * 3
        # xyz轴的位置边界position_min,position_max
        ranges = [r.get_range() for r in self.rails]
        # 生成各个轴的边界
        self.axes_min = toolhead.Coord(*[r[0] for r in ranges], e=0.)
        self.axes_max = toolhead.Coord(*[r[1] for r in ranges], e=0.)
    def get_steppers(self):
        """
        获取所有的xyz轴步进器
        """
        return [s for rail in self.rails for s in rail.get_steppers()]
    def calc_position(self, stepper_positions):
        pos = [stepper_positions[rail.get_name()] for rail in self.rails]
        return [0.5 * (pos[0] + pos[1]), 0.5 * (pos[0] - pos[1]), pos[2]]
    def set_position(self, newpos, homing_axes):
        """
        设置所有步进器的当前位置，并未执行移动操作，仅仅是设置当前位置坐标，之后的移动都依赖该坐标
        """
        for i, rail in enumerate(self.rails):
            rail.set_position(newpos)
            if i in homing_axes:
                self.limits[i] = rail.get_range()
    def note_z_not_homed(self):
        # 该函数会在safe_z_home模块中被调用，设置z轴未归位
        self.limits[2] = (1.0, -1.0)
    def home(self, homing_state):
        # 归位,G28命令直接调用该函数,homing_state保存需要归位的轴形如:[0,1,2]
        # 每个轴都是按顺序独立归位的，homing_state是homing.Homing对象
        for axis in homing_state.get_axes():
            # axis是需要归位的轴0,1,2形式表示xyz轴，stepper.PrinterRail类型
            rail = self.rails[axis]
            # 各个轴的运动范围
            position_min, position_max = rail.get_range()
            # 获取对应轨道归位信息，包括归位速度，限位器位置，归位方向等信息
            hi = rail.get_homing_info()
            homepos = [None, None, None, None]
            # 保存对应轴的限位器位置信息
            homepos[axis] = hi.position_endstop
            # toolhead的起始位置为forcepos，归位时从起始位置移动到限位器的位置homepos
            forcepos = list(homepos)
            # positive_dir 在xy轴中是True，表示往正方向移动，在z轴中是False，表示往负方向移动
            if hi.positive_dir:
                forcepos[axis] -= 1.5 * (hi.position_endstop - position_min)
            else:
                forcepos[axis] += 1.5 * (position_max - hi.position_endstop)
            # 使用对应的轨道执行回归
            homing_state.home_rails([rail], forcepos, homepos)
    def _motor_off(self, print_time):
        self.limits = [(1.0, -1.0)] * 3
    def _check_endstops(self, move):
        end_pos = move.end_pos
        for i in (0, 1, 2):
            if (move.axes_d[i]
                and (end_pos[i] < self.limits[i][0]
                     or end_pos[i] > self.limits[i][1])):
                if self.limits[i][0] > self.limits[i][1]:
                    raise move.move_error("Must home axis first")
                raise move.move_error()
    def check_move(self, move):
        limits = self.limits
        xpos, ypos = move.end_pos[:2]
        if (xpos < limits[0][0] or xpos > limits[0][1]
            or ypos < limits[1][0] or ypos > limits[1][1]):
            self._check_endstops(move)
        if not move.axes_d[2]:
            # Normal XY move - use defaults
            return
        # Move with Z - update velocity and accel for slower Z axis
        self._check_endstops(move)
        z_ratio = move.move_d / abs(move.axes_d[2])
        move.limit_speed(
            self.max_z_velocity * z_ratio, self.max_z_accel * z_ratio)
    def get_status(self, eventtime):
        axes = [a for a, (l, h) in zip("xyz", self.limits) if l <= h]
        return {
            'homed_axes': "".join(axes),
            'axis_minimum': self.axes_min,
            'axis_maximum': self.axes_max,
        }

def load_kinematics(toolhead, config):
    return CoreXYKinematics(toolhead, config)
